<html>
<head>
<title>KF XML Metatype: XML for OSGi metatypes and CM values.</title>
<style type="text/css">

body {
 background: #ffffff;
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:11px;
 color:000000;
 text-align:left;
 font-weight:normal;
}

th {
 background: #d3d3d3;
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:11px;
 color:000000;
 text-align:left;
 font-weight:bold;
 vertical-align:top;
}

.marked {
 font-weight:bold;
}

td {
 background: #ffffff;
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:11px;
 color:000000;
 text-align:left;
 font-weight:normal;
 vertical-align:top;
}


PRE {
 font-family: Courier New, Courier;
 font-size:11px;
 color:#000000;
 text-align:left;
 font-weight:normal;
}

code {
 font-family: Courier New, Courier;
 font-size:11px;
 color:#000000;
 text-align:left;
 font-weight:normal;
}

H1  {
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:19px;
 font-weight:normal;
 color: #000088;
}

H2  {
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:15px;
 font-weight:normal;
 color: #000088;
}

H3  {
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:13px;
 font-weight:normal;
 color: #000088;
}

H4  {
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:11px;
 color: #000088;
}

H5  {
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:9px;
 color: #000088;
}

H6  {
 font-family: Verdana, Arial, Helvetica, sans-serif;
 font-size:7px;
 font-weight:bold;
}

dt { font-weight:bold; }

dd { font-weight:normal; }

div.toc1 {  margin-left: 1em; }

div.toc2 {  margin-left: 2em; }

div.toc3 {  margin-left: 3em; }

div.exampleInner pre { margin-left: 1em; margin-top: 0em; margin-bottom: 0em; }
div.exampleOuter {border: 4px double gray; margin: 0em; padding: 0em; }

div.exampleInner { 
 background-color: #d5dee3;
 border-top-width: 4px;
 border-top-style: double;
 border-top-color: #d3d3d3;
 border-bottom-width: 4px;
 border-bottom-style: double;
 border-bottom-color: #d3d3d3;
 padding: 4px; margin: 0em;
}

div.exampleWrapper { margin: 4px;}

div.exampleHeader { font-weight: bold;  margin: 4px; }

div.schemaComp { border: 4px double gray; margin: 0em 1em; padding: 0em; }

div.compHeader { margin: 4px; font-weight: bold; }

span.schemaComp { color: #A52A2A; }                  

div.compBody { 
  border-top-width: 4px;
  border-top-style: double;
  border-top-color: #d3d3d3;
  padding: 4px ; margin: 0em;
}

.discussion {
  padding: 4px; 
  margin: 0em;
  font-style: italic;
  background-color: #eeeeee;
}
                   

</style>
</head>

<body>

<h1>KF XML Metatype: XML for OSGi metatypes and CM values.</h1>

<a name="1"></a><h2>1. Knopflerfish recommendations May 2004</h2>
<dl>
 <dt>Public version</dt>
 <dd>
 <a href="https://www.knopflerfish.org/XMLMetatype/">https://www.knopflerfish.org/XMLMetatype/</a>
 </dd>
 <dt>Revision</dt>
 <dd>$LastChangedRevision$</dd>
 <dt>Editors</dt>
 <dd>Erik Wistrand
 </dd>
</dl>

<a name="2"></a><h2>2. Abstract</h2>
<i>KF XML Metatype: XML for OSGi metatypes and values</i> is the 
Knopflerfish specification defining OSGi Metatypes and Configuration
 Manager values in XML format.
This format can be used by bundles to define Metatypes, and for an OSGi 
Configuration Manager to store and receive actual configuration values.

<a name="3"></a><h2>3. Status of this document</h2>
Draft.

<a name="4"></a><h2>4. Table of contents</h2>

<div class="toc1"><a href="#1">1. Knopflerfish recommendations May 2004</a></div>
<div class="toc1"><a href="#2">2. Abstract</a></div>
<div class="toc1"><a href="#3">3. Status of this document</a></div>
<div class="toc1"><a href="#4">4. Table of contents</a></div>
<div class="toc1"><a href="#5">5. Introduction</a></div>
<div class="toc2"><a href="#5.1">5.1 Configuration Manager</a></div>
<div class="toc2"><a href="#5.2">5.2 OSGi Metatype API</a></div>
<div class="toc2"><a href="#5.3">5.3 XML Schema</a></div>
<div class="toc2"><a href="#5.4">5.4 Purpose</a></div>
<div class="toc2"><a href="#5.5">5.5 Requirements</a></div>
<div class="toc2"><a href="#5.6">5.6 Terminology</a></div>
<div class="toc1"><a href="#6">6. Metatype specification</a></div>
<div class="toc2"><a href="#6.1">6.1 Services and factories</a></div>
<div class="toc2"><a href="#6.2">6.2 Metatype XML declaration</a></div>
<div class="toc2"><a href="#6.3">6.3 Service and factory definitions - instances of XML Schema</a></div>
<div class="toc2"><a href="#6.4">6.4 Supported data types</a></div>
<div class="toc3"><a href="#6.4.1">6.4.1 Optional attributes</div>
<div class="toc1"><a href="#7">7. Configuration value specification</a></div>
<div class="toc1"><a href="#8">8. Storing Metatype and values in bundle jar files</a></div>
<div class="toc1"><a href="#appendix">Appendix</a></div>
<div class="toc2"><a href="#appendix.draftimpl">Draft implementation</a></div>
<div class="toc2"><a href="#appendix.localization">Localization in the Metatype API</a></div>



<a name="5"></a><h2>5. Introduction</h2>

<a name="5.1"></a><h3>5.1 Configuration Manager</h3>
<p>
The OSGi specification defines a <i>Configuration Manager</i>, CM, capable
of storing configuration data for installed bundles. Such configuration data
is sent to the bundle using instances of <code>java.lang.Dictionary</code>, 
containing name/value pairs. The CM specification itself does not mandate 
any specific means of initializing, storing or specifying such data. This 
is left to the implementation.
</p>

<a name="5.2"></a><h3>5.2 OSGi Metatype API</h3>
<p>
OSGi also specifies a set of <i>Metatype</i> interfaces, which allows an 
OSGi bundle to provide metatype to configurations used by CM. Such metatype
contains
<ul>
 <li>Access to attribute definitions for unique object identifier.
 <li>Available <i>name</i> for an attribute definition.
 <li><i>Type</i> for data in an attribute definition.
 <li>Default values for data in an attribute definition.
</ul>

</p>
<p>
The types supported by the Metatype API is limited to primitive types as string, int, long, short, float, double, char and boolean, plus vectors and arrays of primitive 
types. Vectors and arrays only differ in their run-time format, <code>java.lang.Vector</code> respective java arrays of primitive types.
</p>

<a name="5.3"></a><h3>5.3 XML Schema</h3>
<p>
XML Schemas (<a href="http://www.w3.org/XML/Schema">http://www.w3.org/XML/Schema</a>) are commonly used for specifying metatype information in XML format, 
examples are the Web Services (SOAP) specification, the UPnP specification
and commercial systems for data exchange.
</p>
<p>
XML Schema is a rich specification, which is able to define a much larger set
of types than OSGi Metatype supports. Thus, only a subset of the XML Schema
datatypes need to be supported in KF XML Metatype.
</p>

<a name="5.4"></a><h3>5.4 Purpose</h3>

The purpose of the Metatype XML format is to specify an XML format for

<ul>
 <li><b>Defining</b> metatype that could be stored and read into
     instances of the OSGi Metatype API
 <li><b>Storing</b> data that is used by an OSGi Configuration Manager 
     implementation.
</ul>

A typical usage would be:

<ol>
 <li>The bundle developer specifies, in XML format, the metatypes
     for CM data used by the bundle.
 <li>The bundle developer specifies default values, in XML format,
     for any created CM configurations.
 <li>The above XML data is stored statically in the bundle's jar file
 <li>The bundle is installed.
 <li>A CM user interface reads the bundle's XML data and automatically
     provides an UI.
</ol>

<p>
The last step in the above list could be replaced by a CM utility 
automatically creating configurations from default data, if not otherwise present.
</p>

<a name="5.5"></a><h3>5.5 Requirements</h3>

<ol>
 <li>The Metatype XML specification should re-use existing XML W3C 
     specifications whenever possible. More specifically, XML Schemas
     (<a href="http://www.w3.org/XML/Schema">http://www.w3.org/XML/Schema</a>
    should be used for datatype specification.
 <li>XML Namespaces should be used for defining Metatype specific tags
 <li>Supports for all aspects of the OSGi Metatype API must be available
     in offline format.
</ol>

<a name="5.6"></a><h3>5.6 Terminology</h3>

<dl>
<dt>["xsd:" is used as XMLSchema namespace]</dt>
<dd>If not otherwise specified, all names prefixed by "xsd:" are assumed to
be specified as by <pre>
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
</pre>
</dd>

<dt>["metatype:" is used as Metatype namespace]</dt>
<dd>If not otherwise specified, all names prefixed by "metatype:" are assumed to
be specified as by <pre>
xmlns:metatype = "https://www.knopflerfish.org/XMLMetatype"
</dd>
</pre>

<dt>[CM - <i>OSGi Configuration Manager</i>]</dt>
<dd>CM is used as shorthand for Configuration Manager</dd>

<dt>[PID - Perstistant Identifier]
<dd>
A PID is used by the Configuration Manager to uniquely define a configuration
service or factory. 
</dd>

</dl>

<a name="6"></a><h2>6. Metatype specification</h2>

<a name="6.1"></a><h3>6.1 Services and factories</h3>

<p>
A CM <b>service</b> is a configuration intended to be received 
by a CM <code>ManagedService</code>. At most one CM configuration for a given 
persistant ID (PID) exists at a given time.
</p>

<p>
A CM <b>factory</b> is a configuration intended to be received by a CM 
<code>ManagedServiceFactory</code>. Several CM configurations can exists
for a given PID.
</p>

<a name="6.2"></a><h3>6.2 Metatype XML declaration</h3>

<p>
Metatype declaration in an XML document must use the 
<code>&lt;metatype&gt;</code> element as top level element. 
This element can <b>only</b> 
contain the <code>&lt;xsd:schema&gt;</code>, 
and <code>&lt;metatype:values&gt;</code>
elements. Each of these is optional.
</p>

<p>
Services and factories are specified as <code>complexType</code> elements 
inside the <code>schema</code> element. The only difference between a service and a
factory definition is the <code>maxOccurs</code> value. A factory may occur
more than once in a value document, a service just once.
</p>

<p>
Each service or factory defines a possible PID, represented by an object 
definition containing a set of attribute definitions.
</p>

<div class="schemaComp">
 <div class="compHeader">
  <span class="schemaComp">Metatype declaration</span>
 </div>
 <div class="compBody">
<pre>
&lt;metatype:metatype
        xmlns:metatype = "https://www.knopflerfish.org/XMLMetatype"
        xmlns:xsd      = "http://www.w3.org/2001/XMLSchema"&gt;
 
  &lt;xsd:schema&gt;

   &lt;xsd:complexType name      = "ServiceID"
                    maxOccurs = "1"&gt;
     ...
   &lt;/xsd:complexType&gt;
   ...

   &lt;xsd:complexType name      = "FactoryID"
                    maxOccurs = "unbounded"&gt;
     ...
   &lt;/xsd:complexType&gt;
   ...

  &lt;/xsd:schema&gt;

  &lt;!-- optional default values --&gt;
  &lt;metatype:values&gt;
    ...
  &lt;/metatype:values&gt;

&lt;/metatype:metatype&gt;
</pre>

</div>

</div>



<a name="6.3"></a><h3>6.3 Service and factory definitions - instances of XML complexType</h3>

<p>
All service and factory definitions are instances of a
 <code>complexType</code> specification.<br>
 This <code>complexType</code> fully defines the array of 
<code>AttributeDefinitions</code> in the resulting metatype definition. 
</p>
<p>
A service definition is a complexType with the <code>maxOccurs</code>
attribute set to one.
A factory definition is a complexType with the <code>maxOccurs</code> attribute
larger than one. Default is a service definition.
</p>
<p>
The <b>name</b> of the service/factory <code>complexType</code>
defines the object identifier. During run-time, the name <b>also</b> defines
the persistant ID of configurations. 
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - a simple service Metatype 
specification</div>
<div class="exampleInner">
<pre>
   &lt;xsd:complexType name="service1"&gt;
    &lt;xsd:element   name="string1" type="xsd:string"/&gt;
   &lt;/xsd:complexType&gt; 
</pre>
</div>
</div>

<div class="exampleOuter">
<div class="exampleHeader">Example - a simple factory Metatype 
specification</div>
<div class="exampleInner">
<pre>
   &lt;xsd:complexType name="factory1" maxOccurs="unbounded"&gt;
    &lt;xsd:element   name="int1" type="xsd:int"/&gt;
   &lt;/xsd:complexType&gt; 
</pre>
</div>
</div>

<a name="6.3.1"></a><h3>6.3.1 Vectors and arrays</h3>

<p>
Vector and arrays are specified using the <code>&lt;xsd:sequence&gt;</code>
element. The default format is vector.
</p>

<p>
<div class="discussion">Discussion: Is it better to use arrays as default format? <p>
The nice thing
with arrays is that they have a well-defined item class even if empty. Arrays
are also easier to use for a ManagedService since the can avoid verbose
<code>to&lt;Type&gt;()</code> calls.
</p>
</div>
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - a service using a vector
specification</div>
<div class="exampleInner">
<pre>

   &lt;xsd:complexType name="service2"&gt;
    &lt;xsd:complexType name = "intvector1"&gt;
     &lt;xsd:sequence&gt;
      &lt;xsd:element name = "item" type="xsd:int"/&gt;
     &lt;/xsd:sequence&gt;
    &lt;/xsd:complexType&gt;
   &lt;/xsd:complexType&gt; 
</pre>
</div>
</div>

<p>
<b>Note</b>: <code>&lt;xsd:sequence&gt;</code> must have exacly one element
be named "item".
</p>


<a name="6.3.2"></a><h3>6.3.2 Service/factory descriptions</h3>
<p>
A service's (and factory's) description is set using schema annotations on 
the top level <code>complexType</code>. If no description is set, the
empty string will be used.
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - service description</div>
<div class="exampleInner">
<pre>
   &lt;xsd:complexType name="service1"&gt;
    &lt;xsd:annotation&gt;
     &lt;xsd:documentation&gt;
       <span class="marked">This is a service annotation</span>
     &lt;/xsd:documentation&gt;
    &lt;/xsd:annotation&gt;
    ...
   &lt;/xsd:complexType&gt; 
</pre>
</div>
</div>

<a name="6.3.2.1"></a><h3>6.3.2.1 Service/factory icon</h3>

<p>
A service/factory icon URL can be set by adding an option <code>iconURL</code>
attribute to the service's defining element.
</p>
<p>
URLs starting with "/" should be considered relative to the defining
bundle's jar file, i.e, bundle resource names.
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - service icon</div>
<div class="exampleInner">
<pre>
 &lt;xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" &gt;
   &lt;xsd:complexType name    = "service1"
                    iconURL = "/image.gif"&gt;
   ...
</pre>
</div>
</div>

</p>

<a name="6.3.3"></a><h3>6.3.3 Attribute descriptions</h3>
<p>
An attribute description is set using schema annotations on 
the attribues defining element. If no description is set, the
empty string will be used.
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - attribute description</div>
<div class="exampleInner">
<pre>
   &lt;xsd:complexType name="service1"&gt;
    &lt;xsd:element   name="string1" type="xsd:string"&gt;
     &lt;xsd:annotation&gt;
      &lt;xsd:documentation&gt;
       <span class="marked">This is an attribute annotation</span>
      &lt;/xsd:documentation&gt;
     &lt;/xsd:annotation&gt;
    &lt;/xsd:element&gt;
   &lt;/xsd:complexType&gt; 
</pre>
</div>
</div>

<a name="6.3.3.1"></a><h4>6.3.3.1 Localized descriptions</h4>



<p>
Locale specific description strings can be set on annotations, using the 
standard <code>xml:lang</code> attribute:
</p>

<p>
<div class="discussion">Discussion: The Metatype API has some oddities which
makes actual runtime implementation hard. Thus, the draft implementation
of the KF XML does not yet read localized data. See <a href="#appendix.localization">appendix</a> for more info.
</div>
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - inline, localized description in two languages</div>
<div class="exampleInner">
<pre>
&lt;xsd:element   name="string1" type="xsd:string"&gt;
 &lt;xsd:annotation&gt;
  &lt;xsd:documentation xml:lang="en"&gt;
      This is the English description.
  &lt;/xsd:documentation&gt;
  &lt;xsd:documentation xml:lang="se"&gt;
      Detta �r beskrivningen p� svenska.
  &lt;/xsd:documentation&gt;
 &lt;/xsd:annotation&gt;
&lt;/xsd:element&gt;
</pre>

</div>
</div>

<p>
Optionally, the <code>&lt;xsd:appInfo&gt;</code> element can be used to specify a an 
URL or resource file to localization property file. The <code>appInfo</code>
should then be set on the object class definition element. 
Standard file name expansion for locales may be done on
the URL.
</p>

<p>
URLs starting with "/" should be considered relative to the defining bundle's jar file, i.e, bundle resource names. 
</p>

<p>
The key for lookup in the external localization file
will be the attribute's ID, plus either <code>".desc"</code> for attribute
description and, optionally, <code>".name"</code> for attribute names.
</p>
<p>
If the the key is not found, the <code>xsd:documentation</code> will be 
searched for default values.
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - external, localized description</div>
<div class="exampleInner">
<pre>
   &lt;xsd:complexType name="service1"&gt;
    &lt;xsd:annotation&gt;
     &lt;xsd:appInfo&gt;/settings.props&lt;xsd:/appInfo&gt;
    &lt;/xsd:annotation&gt;

    &lt;xsd:element   name="string1" type="xsd:string"/&gt;

   ...
</pre>
<p>
The file <code>/settings.props</code> in the bundle jar should 
contain lines as:
</p>
<pre>
string1.desc=This is the description for string1
string1.name=First string
</pre>

<p>
A Swedish translation <code>/settings_se.props</code> in the bundle jar could 
contain lines as:
</p>
<pre>
string1.desc=Humdihumdididum
string1.name=Chef #1
</pre>

</div>
</div>
</p>


<a name="6.4"></a><h3>6.4 Supported data types</h3>

<p>
The <b>name</b> of each service/factory data element represent the
ID of an attribute definition. If nothing else is specified in the element
annotation, the name of the attribute equals its ID.
</p>

<p>
The <b>type</b> of each service/factory data element represent the type of 
the attribute definition.
</p>

<p>
<code>&lt;xsd:annotation&gt;</code> elements can optionally be used to set 
an attribute or enumeration description.
</p>

<div class="schemaComp">
 <div class="compHeader">
  <span class="schemaComp">Data types</span>
 </div>
<div class="compBody">

<table>
 <tr>
  <th>Datatype</th>
  <th>XML specification</th>
  <th>Java representation</th>
  <th>Comment</th>
 </tr>

 <tr>
  <th colspan=4>Primitive types</th>
 </tr>

 <tr>
  <td>string</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:string"/&gt;</code>
  <td>java.lang.String</td>
  <td rowspan="8">NAME is the ID and default name of the Metatype 
      <code>AttibuteDefinition</code>.
      <p>
      NAME must be possible to use as a valid XML tag name.
      </p>
   </td>
 </tr>

 <tr>
  <td>integer</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:int"/&gt;</code>
  <td>java.lang.Integer</td>
  <td></td>
 </tr>

 <tr>
  <td>long</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:long"/&gt;</code>
  <td>java.lang.Long</td>
  <td></td>
 </tr>

 <tr>
  <td>short</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:short"/&gt;</code>
  <td>java.lang.Short</td>
  <td></td>
 </tr>

 <tr>
  <td>char</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:char"/&gt;</code>
  <td>java.lang.Character</td>
  <td></td>
 </tr>


 <tr>
  <td>float</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:float"/&gt;</code>
  <td>java.lang.Float</td>
  <td></td>
 </tr>

 <tr>
  <td>double</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:double"/&gt;</code>
  <td>java.lang.Double</td>
  <td></td>
 </tr>


 <tr>
  <td>boolean</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:boolean"/&gt;</code>
  <td>java.lang.Boolean</td>
  <td></td>
 </tr>

 <tr>
  <td>BigInteger</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:integer"/&gt;
  <td>java.math.BigInteger</td>
  <td>
If running on a JVM without the <tt>BigInteger</tt> class, <tt>long</tt> is used instead.
  </td>
 </tr>

 <tr>
  <td>BigDecimal</td>
  <td><code>&lt;xsd:element name="<b>NAME</b>" type="xsd:decimal"/&gt;</code>
  <td>java.math.BigDecimal</td>
  <td>
If running on a JVM without the <tt>BigDecimal</tt> class, <tt>double</tt> is used instead.
  </td>
 </tr>

 <tr>
  <th colspan=4>Primitive types with restrictions</th>
 </tr>

 <tr>
  <td>Enumerated types</td>
  <td>
<pre>
&lt;xsd:simpleType name = "NAME"&gt;
 &lt;xsd:restriction base="TYPE"&gt;
  &lt;xsd:enumeration value="VALUE1"/&gt;
  &lt;xsd:enumeration value="VALUE2"/&gt;
  ...
 &lt;/xsd:restriction&gt;
&lt;/xsd:simpleType&gt;
</pre>
  </td>
  <td>As defined by TYPE. See primitive types above.
  </td>
  <td>Enumeration values will be stored as attribute definition <i>option values</i>.
  </td>
 </tr>

 <tr>
  <td>Enumerated types with labels</td>
  <td>
<pre>
&lt;xsd:simpleType name = "NAME"&gt;
 &lt;xsd:restriction base="TYPE"&gt;
  &lt;xsd:enumeration value="VALUE1"/&gt;
   &lt;xsd:annotation&gt;
    &lt;xsd:documentation&gt;
     Label for VALUE1
    &lt;/xsd:documentation&gt;
   &lt;/xsd:annotation&gt;  
  ...
 &lt;/xsd:restriction&gt;
&lt;/xsd:simpleType&gt;
</pre>
  </td>
  <td>As defined by TYPE. See primitive types above.
  </td>
  <td>If <code>&lt;xsd:annotation&gt;</code> elements are added to an
<code>enumeration</code>, the annotation documentation will be used as
the attribute definition's <i>option label</i>. If no annotation documentations
are found, the values are used as labels.
  </td>
 </tr>


 <tr>
  <th colspan=4>Vectors and arrays</th>
 </tr>

 <tr>
  <td>Vector</td>
  <td><pre>
&lt;xsd:complexType 
     name="NAME"&gt;
 &lt;xsd:sequence
     [array="false"]
     [maxOccurs="MAX"]&gt;
  PRIMITIVE_TYPE
 &lt;/xsd:sequence&gt;
&lt;/xsd:complexType&gt;
</pre>
  </td>
  <td>
   java.util.Vector, where each item is of the type specified by PRIMITIVE_TYPE
<p>
Note: The specifed PRIMITIVE_TYPE <b>must</b> have a name of "item"
</p>
  </td>
  <td>
   The default value for the <code>array</code> property is "false". <br>
   The default value for the <code>maxOccurs</code> property is 
<code>java.lang.Integer.MAX_VALUE</code>. <br>
  </td>
 </tr>

 <tr>
  <td>Array</td>
  <td><pre>
&lt;xsd:complexType
     name="<b>NAME</b>"
     [maxOccurs="MAX"]&gt;
 &lt;xsd:sequence array="true"&gt;
  PRIMITIVE_TYPE
 &lt;/xsd:sequence&gt;
&lt;/xsd:complexType&gt;
</pre>
  </td>
  <td>
   Java array, where each item is of the <b>unboxed</b> type specified by
   PRIMITIVE_TYPE.
<p>
Note: The specifed PRIMITIVE_TYPE <b>must</b> have a name of "item"
</p>

  </td>
<td>
Resulting arrays will be represented as:
<table>
 <tr><th>Primitive type</th> <th>Array type</th></tr>
 <tr><td>Integer</td>        <td>int[]</td></tr>
 <tr><td>Boolean</td>        <td>boolean[]</td></tr>
 <tr><td>Double</td>         <td>double[]</td></tr>
 <tr><td>Float</td>          <td>float[]</td></tr>
 <tr><td>Long</td>           <td>long[]</td></tr>
 <tr><td>Short</td>          <td>short[]</td></tr>
 <tr><td>Character</td>      <td>char[]</td></tr>
 <tr><td>String</td>         <td>String[]</td></tr>
 <tr><td>BigInteger</td>     <td>BigInteger[]</td></tr>
 <tr><td>BigDecimal</td>     <td>BigDecimal[]</td></tr>
</table>
</td>
 </tr>

</table>
</div>
</div>

<a name="6.4.1"></a><h4>6.4.1 Optional attributes</h4>

<p>
Attributes can be specified to be optional by setting the 
<code>minOccurs</code> attribute to zero on the attribute element. 
By default, attributes are required -- which also can be specified by
setting <code>minOccurs</code> to one. 
</p>

<p>
Setting <code>minOccurs &gt; 1</code> is not allowed.
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - specifying an optional attribute</div>
<div class="exampleInner">
<pre>
&lt;xsd:element   name      = "string1" 
               type      = "xsd:string"
               minOccurs = "0"/&gt;
</pre>

</div>
</div>


<a name="7"></a><h2>7. Configuration value specification</h2>

<p>
Configuration values are specified using the 
<code>&lt;metatype:values&gt;</code> 
element. This contains a set of XML elements as defined by the Metatype 
schema.
</p>
<p>
A <code>&lt;metatype:values&gt;</code> element can be embedded in 
<code>&lt;metatype:metatype&gt;</code>. The values should then be considered default values for the specified metatypes.
</p>

<div class="schemaComp">
<div class="compHeader">
<span class="schemaComp">Configuration value declaration</span>
</div>
<div class="compBody">
<pre>
&lt;?xml version="1.0"?&gt;

  &lt;metatype:values
        xmlns:metatype = "https://www.knopflerfish.org/XMLMetatype"&gt;

    [VALUE_DECLARATIONS]

  &lt;/metatype:values&gt;
</pre>
</div>
</div>
</div>

<p>
[VALUE_DECLARATIONS] is thus a sequence of top level elements, named as 
the PIDs used when defining the metatypes. Each such PID element contains
elements matching the attribute definitions.
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - a value declaration for the simple service</div>
<div class="exampleInner">
<pre>
  &lt;service1&gt;
   &lt;string1&gt;this the string value&lt;/string1&gt;
  &lt;/service1&gt;   
</pre>
</div>
</div>

<p>
</p>

<div class="exampleOuter">
<div class="exampleHeader">Example - a value declaration defining a vector/array</div>
<div class="exampleInner">
<pre>
  &lt;service2&gt;
   &lt;intvector1&gt;
    &lt;item&gt;1&lt;/item&gt;
    &lt;item&gt;2&lt;/item&gt;
    &lt;item&gt;3&lt;/item&gt;
   &lt;/intvector1&gt;
 &lt;/service2&gt;
</pre>
</div>
</div>



<a name="7.2"></a><h2>7.2 Typed value specifications</h2>
<p>
As value specifications are instances of a schema, the system is assumed
to have access to the schema specification when parsing a value document.
This can be accomplished by at least three different methods:
</p>

<ul>
 <li>Storing the schema specification in the same file as the value, i.e
     prefix the value specification with the appropiate 
     <code>metatype:services</code> and/or <code>metatype:factories</code>
     elements.
<p>
</p>

 <li>Storing the metatype XML documents in an index related to the 
     value document.
<p>
</p>

 <li>Using the standard schema type attribute <code>type="TYPE"</code> 
on each value element.
<p>
<div class="exampleOuter">
<div class="exampleHeader">Example - a typed value document</div>
<div class="exampleInner">
<pre>
  &lt;service3&gt;
   &lt;string1    type="xsd:string"/&gt;
   &lt;intvector1 type="xsd:int" array="true"&gt;
    &lt;item&gt;1&lt;/item&gt;
    &lt;item&gt;2&lt;/item&gt;
    &lt;item&gt;3&lt;/item&gt;
   &lt;/intvector1&gt;
 &lt;/service2&gt;
</pre>
</div>
</div>
</p>

</ul>




<a name="8"></a><h2>8. Storing Metatype and values in bundle jar files</h2>

<p>
A bundle can store URLs to metatype and value document in its Manifest 
attributes. The run-time system is then responsible for reading these 
attributes when the bundle is started (or deployed) and converting them to 
suitable run-time format (Metatype API and/or CM dictionaries).
</p>

<p>
URLs starting with "/" should be considered relative to the defining
bundle's jar file, i.e, bundle resource names.
</p>


<div class="schemaComp">
<div class="compHeader">
 <span class="schemaComp">Manifest attributes</span>
</div>
<div class="compBody">

<table>
 <tr>
  <th>Manifest attribute</th>
  <th>Description</th>
  <th>Default value</th>
 </tr>
 <tr>
  <td>Bundle-MetatypeURL</td>
  <td>URL to XML document describing metatype<br>
  </td>
  <td>/metatype.xml</td>
 </tr>

 <tr>
  <td>Bundle-CMDefaultsURL</td>
  <td>URL to XML document with CM default values<br>
  </td>
  <td>/cmdefaults.xml</td>
 </tr>

</table>
</div>
</div>
</div>


<a name="appendix"></a><h2>Appendix</h2>

<a name="appendix.draftimpl"></a><h3>Draft implementation</h3>

<p>
A draft implementation is available at<br>
<a href="https://github.com/knopflerfish/knopflerfish.org/tree/master/osgi/bundles/metatype">https://github.com/knopflerfish/knopflerfish.org/tree/master/osgi/bundles/metatype</a>
</p>

<p>
See <a href="https://www.knopflerfish.org">https://www.knopflerfish.org</a> for details on
how to access the code repository.
</p>

<a name="appendix.localization"></a><h3>Localization in the Metatype API</h3>


<ol>
<li> The Metatype API specifies that a MetaTypeProvider can return
   ObjectClassDefinitions based on a PID and a Locale.

<li> This implies that each ObjectClassDefinition, per Locale, should have
   it's own ID, since every ObjectClassDefinition is specified to have
   a unique ID.

<li> 2) leads to a very cumbersome mapping of ObjectClassDefinitions
   to CM PIDs since they never can implemented as equal, even if this
   would be possible in a given situation (as it very often is)

<li> 1) also leads to a conceptually odd model, where a given Locale
   actually could specify a ObjectClassDefinition with a *different*
   set of attributes than another OCD with with the same PID. At, least,
   the API does not specify that the attributes must be same.

<li> 1) also leads to an expensive implementation situation where the
   number of instances of OCDs created by a MTP multiplies by the
   number of supported locales, even if the actual language data is
   held  in single instances if AttributeDefinition

</ol>

<p>
Conclusion: The Locale-specific methods
<pre>
 OCD.getName, OCD.getDescription,  OCD.getIcon
 AD.getName, AD.getDescription and AD.getOptionLabels
</pre>

should be themselves take a Locale argument, not the MetatypeProvider.
</p>

<p>
(...and while I'm at it, the getIcon argument "size" could just as easily be dumped since there is no chance of relying on the results. Also, returning a stream from getIcon effectively removes
any possibility of remoting OCD instances. an URL string would be much better) 
</p>

</body>
</html>
